home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Technology Seed / August 1998 ADC Seed CD.toast / Mac OS 8.5b2 / allegro-b2-pseudo-SDK / PInterfaces / Navigation.p < prev    next >
Encoding:
Text File  |  1998-07-17  |  16.0 KB  |  418 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        Navigation.p
  3.  
  4.      Contains:    Navigation Services Interfaces
  5.  
  6.      Version:    Technology:    1.1
  7.                  Release:    Allego Seed, Use with 3.1 Universal Interfaces
  8.  
  9.      Copyright:    © 1996-1998 by Apple Computer, Inc., all rights reserved
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT Navigation;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __NAVIGATION__}
  28. {$SETC __NAVIGATION__ := 1}
  29.  
  30. {$I+}
  31. {$SETC NavigationIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __MACTYPES__}
  35. {$I MacTypes.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __APPLEEVENTS__}
  38. {$I AppleEvents.p}
  39. {$ENDC}
  40. {$IFC UNDEFINED __TRANSLATION__}
  41. {$I Translation.p}
  42. {$ENDC}
  43. {$IFC UNDEFINED __MACWINDOWS__}
  44. {$I MacWindows.p}
  45. {$ENDC}
  46. {$IFC UNDEFINED __CODEFRAGMENTS__}
  47. {$I CodeFragments.p}
  48. {$ENDC}
  49.  
  50.  
  51.  
  52. {$PUSH}
  53. {$ALIGN MAC68K}
  54. {$LibExport+}
  55.  
  56.  
  57. CONST
  58.     kNavMissingKindStringErr    = -5699;
  59.     kNavInvalidCustomControlMessageErr = -5698;
  60.     kNavCustomControlMessageFailedErr = -5697;
  61.     kNavInvalidSystemConfigErr    = -5696;
  62.  
  63.  
  64.     kNavDialogOptionsVersion    = 0;
  65.     kNavReplyRecordVersion        = 0;
  66.     kNavCBRecVersion            = 0;
  67.     kNavFileOrFolderVersion        = 0;
  68.     kNavMenuItemSpecVersion        = 0;
  69.  
  70.  
  71. TYPE
  72.     NavDataVersion                        = UInt16;
  73.  
  74. CONST
  75.                                                                 {  input action codes for NavAskSaveChanges()  }
  76.     kNavSaveChangesClosingDocument = 1;
  77.     kNavSaveChangesQuittingApplication = 2;
  78.     kNavSaveChangesOther        = 0;
  79.  
  80.  
  81. TYPE
  82.     NavAskSaveChangesAction                = UInt32;
  83.  
  84. CONST
  85.                                                                 {  result codes for NavAskSaveChanges()  }
  86.     kNavAskSaveChangesSave        = 1;
  87.     kNavAskSaveChangesCancel    = 2;
  88.     kNavAskSaveChangesDontSave    = 3;
  89.  
  90.  
  91. TYPE
  92.     NavAskSaveChangesResult                = UInt32;
  93.  
  94. CONST
  95.                                                                 {  result codes for NavAskDiscardChanges()  }
  96.     kNavAskDiscardChanges        = 1;
  97.     kNavAskDiscardChangesCancel    = 2;
  98.  
  99.  
  100. TYPE
  101.     NavAskDiscardChangesResult            = UInt32;
  102.  
  103. CONST
  104.                                                                 {  which elements are being filtered for objects:  }
  105.     kNavFilteringBrowserList    = 0;
  106.     kNavFilteringFavorites        = 1;
  107.     kNavFilteringRecents        = 2;
  108.     kNavFilteringShortCutVolumes = 3;
  109.     kNavFilteringLocationPopup    = 4;
  110.  
  111.  
  112. TYPE
  113.     NavFilterModes                        = INTEGER;
  114.     NavFileOrFolderInfoPtr = ^NavFileOrFolderInfo;
  115.     NavFileOrFolderInfo = RECORD
  116.         version:                UInt16;
  117.         isFolder:                BOOLEAN;
  118.         visible:                BOOLEAN;
  119.         creationDate:            UInt32;
  120.         modificationDate:        UInt32;
  121.         CASE INTEGER OF
  122.         0: (
  123.             locked:                BOOLEAN;                                {  file is locked  }
  124.             resourceOpen:        BOOLEAN;                                {  resource fork is opened  }
  125.             dataOpen:            BOOLEAN;                                {  data fork is opened  }
  126.             reserved1:            BOOLEAN;
  127.             dataSize:            UInt32;                                    {  size of the data fork  }
  128.             resourceSize:        UInt32;                                    {  size of the resource fork  }
  129.             finderInfo:            FInfo;                                    {  more file info:  }
  130.             finderXInfo:        FXInfo;
  131.            );
  132.         1: (
  133.             shareable:            BOOLEAN;
  134.             sharePoint:            BOOLEAN;
  135.             mounted:            BOOLEAN;
  136.             readable:            BOOLEAN;
  137.             writeable:            BOOLEAN;
  138.             reserved2:            BOOLEAN;
  139.             numberOfFiles:        UInt32;
  140.             finderDInfo:        DInfo;
  141.             finderDXInfo:        DXInfo;
  142.             reserved3:            PACKED ARRAY [0..213] OF CHAR;
  143.            );
  144.     END;
  145.  
  146.     NavEventDataInfoPtr = ^NavEventDataInfo;
  147.     NavEventDataInfo = RECORD
  148.         CASE INTEGER OF
  149.         0: (
  150.             event:                EventRecordPtr;                            {  for event processing  }
  151.             );
  152.         1: (
  153.             param:                Ptr;                                    {  points to event specific data  }
  154.             );
  155.     END;
  156.  
  157.     NavEventDataPtr = ^NavEventData;
  158.     NavEventData = RECORD
  159.         eventDataParms:            NavEventDataInfo;                        {  the event data  }
  160.         itemHit:                SInt16;                                    {  the dialog item number  }
  161.     END;
  162.  
  163.     NavContext                            = UInt32;
  164.     NavCBRecPtr = ^NavCBRec;
  165.     NavCBRec = RECORD
  166.         version:                UInt16;
  167.         context:                NavContext;                                {  used by customization code to call Navigation Services  }
  168.         window:                    WindowPtr;                                {  the dialog  }
  169.         customRect:                Rect;                                    {  local coordinate rectangle of customization area  }
  170.         previewRect:            Rect;                                    {  local coordinate rectangle of the preview area  }
  171.         eventData:                NavEventData;
  172.         reserved:                PACKED ARRAY [0..221] OF CHAR;
  173.     END;
  174.  
  175.  
  176. CONST
  177.     kNavCBEvent                    = 0;                            {  an event has occurred (update, idle events, etc.)  }
  178.     kNavCBCustomize                = 1;                            {  protocol for negotiating customization space  }
  179.     kNavCBStart                    = 2;                            {  the navigation dialog is starting up  }
  180.     kNavCBTerminate                = 3;                            {  the navigation dialog is closing down  }
  181.     kNavCBAdjustRect            = 4;                            {  the navigation dialog is being resized  }
  182.     kNavCBNewLocation            = 5;                            {  user has chosen a new location in the browser  }
  183.     kNavCBShowDesktop            = 6;                            {  user has navigated to the desktop  }
  184.     kNavCBSelectEntry            = 7;                            {  user has made a selection in the browser  }
  185.     kNavCBPopupMenuSelect        = 8;                            {  signifies that a popup menu selection was made  }
  186.     kNavCBAccept                = 9;                            {  user has accepted the navigation dialog  }
  187.     kNavCBCancel                = 10;                            {  user has cancelled the navigation dialog  }
  188.     kNavCBAdjustPreview            = 11;                            {  preview button was clicked or the preview was resized  }
  189.  
  190.  
  191. TYPE
  192.     NavEventCallbackMessage                = SInt32;
  193.     NavCallBackUserData                    = Ptr;
  194. { for events and customization: }
  195. {$IFC TYPED_FUNCTION_POINTERS}
  196.     NavEventProcPtr = PROCEDURE(callBackSelector: NavEventCallbackMessage; callBackParms: NavCBRecPtr; callBackUD: UNIV Ptr);
  197. {$ELSEC}
  198.     NavEventProcPtr = ProcPtr;
  199. {$ENDC}
  200.  
  201. { for preview support: }
  202. {$IFC TYPED_FUNCTION_POINTERS}
  203.     NavPreviewProcPtr = FUNCTION(callBackParms: NavCBRecPtr; callBackUD: UNIV Ptr): BOOLEAN;
  204. {$ELSEC}
  205.     NavPreviewProcPtr = ProcPtr;
  206. {$ENDC}
  207.  
  208. { filtering callback information: }
  209. {$IFC TYPED_FUNCTION_POINTERS}
  210.     NavObjectFilterProcPtr = FUNCTION(VAR theItem: AEDesc; info: UNIV Ptr; callBackUD: UNIV Ptr; filterMode: NavFilterModes): BOOLEAN;
  211. {$ELSEC}
  212.     NavObjectFilterProcPtr = ProcPtr;
  213. {$ENDC}
  214.  
  215.     NavEventUPP = UniversalProcPtr;
  216.     NavPreviewUPP = UniversalProcPtr;
  217.     NavObjectFilterUPP = UniversalProcPtr;
  218.  
  219. CONST
  220.     uppNavEventProcInfo = $00000FC0;
  221.     uppNavPreviewProcInfo = $000003D0;
  222.     uppNavObjectFilterProcInfo = $00002FD0;
  223.  
  224. FUNCTION NewNavEventProc(userRoutine: NavEventProcPtr): NavEventUPP;
  225.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  226.     INLINE $2E9F;
  227.     {$ENDC}
  228.  
  229. FUNCTION NewNavPreviewProc(userRoutine: NavPreviewProcPtr): NavPreviewUPP;
  230.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  231.     INLINE $2E9F;
  232.     {$ENDC}
  233.  
  234. FUNCTION NewNavObjectFilterProc(userRoutine: NavObjectFilterProcPtr): NavObjectFilterUPP;
  235.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  236.     INLINE $2E9F;
  237.     {$ENDC}
  238.  
  239. PROCEDURE CallNavEventProc(callBackSelector: NavEventCallbackMessage; callBackParms: NavCBRecPtr; callBackUD: UNIV Ptr; userRoutine: NavEventUPP);
  240.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  241.     INLINE $205F, $4E90;
  242.     {$ENDC}
  243.  
  244. FUNCTION CallNavPreviewProc(callBackParms: NavCBRecPtr; callBackUD: UNIV Ptr; userRoutine: NavPreviewUPP): BOOLEAN;
  245.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  246.     INLINE $205F, $4E90;
  247.     {$ENDC}
  248.  
  249. FUNCTION CallNavObjectFilterProc(VAR theItem: AEDesc; info: UNIV Ptr; callBackUD: UNIV Ptr; filterMode: NavFilterModes; userRoutine: NavObjectFilterUPP): BOOLEAN;
  250.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  251.     INLINE $205F, $4E90;
  252.     {$ENDC}
  253.  
  254. CONST
  255.     kNavCtlShowDesktop            = 0;                            {     show desktop,                 parms = nil  }
  256.     kNavCtlSortBy                = 1;                            {     sort key field,             parms->NavSortKeyField  }
  257.     kNavCtlSortOrder            = 2;                            {     sort order,                    parms->NavSortOrder  }
  258.     kNavCtlScrollHome            = 3;                            {     scroll list home,            parms = nil  }
  259.     kNavCtlScrollEnd            = 4;                            {     scroll list end,            parms = nil  }
  260.     kNavCtlPageUp                = 5;                            {     page list up,                parms = nil  }
  261.     kNavCtlPageDown                = 6;                            {     page list down,                parms = nil  }
  262.     kNavCtlGetLocation            = 7;                            {     get current location,        parms<-AEDesc  }
  263.     kNavCtlSetLocation            = 8;                            {     set current location,        parms->AEDesc  }
  264.     kNavCtlGetSelection            = 9;                            {     get current selection,        parms<-AEDescList  }
  265.     kNavCtlSetSelection            = 10;                            {     set current selection,        parms->AEDescList  }
  266.     kNavCtlShowSelection        = 11;                            {     make selection visible,        parms = nil  }
  267.     kNavCtlOpenSelection        = 12;                            {     open view of selection,        parms = nil  }
  268.     kNavCtlEjectVolume            = 13;                            {     eject volume,                parms->vRefNum  }
  269.     kNavCtlNewFolder            = 14;                            {     create a new folder,        parms->StringPtr  }
  270.     kNavCtlCancel                = 15;                            {     cancel dialog,                parms = nil  }
  271.     kNavCtlAccept                = 16;                            {     accept dialog default,        parms = nil  }
  272.     kNavCtlIsPreviewShowing        = 17;                            {     query preview status,        parms<-Boolean  }
  273.     kNavCtlAddControl            = 18;                            {   add one control to dialog,    parms->ControlHandle  }
  274.     kNavCtlAddControlList        = 19;                            {     add control list to dialog,    parms->Handle (DITL rsrc)  }
  275.     kNavCtlGetFirstControlID    = 20;                            {     get 1st control ID,            parms<-UInt16  }
  276.     kNavCtlSelectCustomType        = 21;                            {     select a custom menu item    parms->NavMenuItemSpec  }
  277.     kNavCtlSelectAllType        = 22;                            {   select an "All" menu item    parms->SInt16  }
  278.     kNavCtlGetEditFileName        = 23;                            {     get save dlog's file name    parms<-StringPtr  }
  279.     kNavCtlSetEditFileName        = 24;                            {     set save dlog's file name    parms->StringPtr  }
  280.     kNavCtlSelectEditFileName    = 25;                            {     select save dlog file name    parms->ControlEditTextSelectionRec (v1.1 only)  }
  281.  
  282.  
  283. TYPE
  284.     NavCustomControlMessage                = SInt32;
  285.  
  286. CONST
  287.     kNavAllKnownFiles            = 0;
  288.     kNavAllReadableFiles        = 1;
  289.     kNavAllFiles                = 2;
  290.  
  291.  
  292. TYPE
  293.     NavPopupMenuItem                    = UInt16;
  294.  
  295. CONST
  296.     kNavSortNameField            = 0;
  297.     kNavSortDateField            = 1;
  298.  
  299.  
  300. TYPE
  301.     NavSortKeyField                        = UInt16;
  302.  
  303. CONST
  304.     kNavSortAscending            = 0;
  305.     kNavSortDescending            = 1;
  306.  
  307.  
  308. TYPE
  309.     NavSortOrder                        = UInt16;
  310.  
  311. CONST
  312.     kNavDefaultNavDlogOptions    = $000000E4;                    {  use defaults for all the options  }
  313.     kNavNoTypePopup                = $00000001;                    {  don't show file type/extension popup on Open/Save  }
  314.     kNavDontAutoTranslate        = $00000002;                    {  don't automatically translate on Open  }
  315.     kNavDontAddTranslateItems    = $00000004;                    {  don't add translation choices on Open/Save  }
  316.     kNavAllFilesInPopup            = $00000010;                    {  "All Files" menu item in the type popup on Open  }
  317.     kNavAllowStationery            = $00000020;                    {  allow saving of stationery files  }
  318.     kNavAllowPreviews            = $00000040;                    {  allow to show previews  }
  319.     kNavAllowMultipleFiles        = $00000080;                    {  allow multiple items to be selected  }
  320.     kNavAllowInvisibleFiles        = $00000100;                    {  allow invisible items to be shown  }
  321.     kNavDontResolveAliases        = $00000200;                    {  don't resolve aliases  }
  322.     kNavSelectDefaultLocation    = $00000400;                    {  make the default location the browser selection  }
  323.     kNavSelectAllReadableItem    = $00000800;                    {  make the dialog select "All Readable Documents" on Open  }
  324.  
  325.  
  326. TYPE
  327.     NavDialogOptionFlags                = UInt32;
  328.  
  329. CONST
  330.     kNavTranslateInPlace        = 0;                            {     translate in place, replacing translation source file (default for Save)  }
  331.     kNavTranslateCopy            = 1;                            {     translate to a copy of the source file (default for Open)  }
  332.  
  333.  
  334. TYPE
  335.     NavTranslationOptions                = UInt32;
  336.     NavMenuItemSpecPtr = ^NavMenuItemSpec;
  337.     NavMenuItemSpec = RECORD
  338.         version:                UInt16;
  339.         menuCreator:            OSType;
  340.         menuType:                OSType;
  341.         menuItemName:            Str255;
  342.         reserved:                PACKED ARRAY [0..244] OF CHAR;
  343.     END;
  344.  
  345.     NavMenuItemSpecHandle                = ^NavMenuItemSpecPtr;
  346.     NavTypeListPtr = ^NavTypeList;
  347.     NavTypeList = RECORD
  348.         componentSignature:        OSType;
  349.         reserved:                INTEGER;
  350.         osTypeCount:            INTEGER;
  351.         osType:                    ARRAY [0..0] OF OSType;
  352.     END;
  353.  
  354.     NavTypeListHandle                    = ^NavTypeListPtr;
  355.     NavDialogOptionsPtr = ^NavDialogOptions;
  356.     NavDialogOptions = RECORD
  357.         version:                UInt16;
  358.         dialogOptionFlags:        NavDialogOptionFlags;                    {  option flags for affecting the dialog's behavior  }
  359.         location:                Point;                                    {  top-left location of the dialog, or (-1,-1) for default position  }
  360.         clientName:                Str255;
  361.         windowTitle:            Str255;
  362.         actionButtonLabel:        Str255;                                    {  label of the default button (or null string for default)  }
  363.         cancelButtonLabel:        Str255;                                    {  label of the cancel button (or null string for default)  }
  364.         savedFileName:            Str255;                                    {  default name for text box in NavPutFile (or null string for default)  }
  365.         message:                Str255;                                    {  custom message prompt (or null string for default)  }
  366.         preferenceKey:            UInt32;                                    {  a key for to managing preferences for using multiple utility dialogs  }
  367.         popupExtension:            Handle;                                    {  extended popup menu items, an array of NavMenuItemSpecs  }
  368.         reserved:                PACKED ARRAY [0..493] OF CHAR;
  369.     END;
  370.  
  371. { data returned by the utility dialogs: }
  372.     NavReplyRecordPtr = ^NavReplyRecord;
  373.     NavReplyRecord = RECORD
  374.         version:                UInt16;
  375.         validRecord:            BOOLEAN;                                {  open/save: true if the user confirmed a selection, false on cancel  }
  376.         replacing:                BOOLEAN;                                {  save: true if the user is overwriting an existing object for save  }
  377.         isStationery:            BOOLEAN;                                {  save: true if the user wants to save an object as stationery  }
  378.         translationNeeded:        BOOLEAN;                                {  save: translation is 'needed', open: translation 'has taken place'  }
  379.         selection:                AEDescList;                                {  open/save: list of AppleEvent descriptors of the chosen object(s)  }
  380.         keyScript:                ScriptCode;                                {  open/save: script in which the name of each item in 'selection' is to be displayed  }
  381.         fileTranslation:        ^FileTranslationSpecPtr;                {  open/save: list of file translation specs of the chosen object(s), if translation is needed  }
  382.         reserved1:                UInt32;
  383.         reserved:                PACKED ARRAY [0..230] OF CHAR;
  384.     END;
  385.  
  386. FUNCTION NavLoad: OSErr;
  387. FUNCTION NavUnload: OSErr;
  388. FUNCTION NavLibraryVersion: UInt32;
  389. FUNCTION NavGetDefaultDialogOptions(VAR dialogOptions: NavDialogOptions): OSErr;
  390.  
  391. FUNCTION NavGetFile(VAR defaultLocation: AEDesc; VAR reply: NavReplyRecord; VAR dialogOptions: NavDialogOptions; eventProc: NavEventUPP; previewProc: NavPreviewUPP; filterProc: NavObjectFilterUPP; typeList: NavTypeListHandle; callBackUD: UNIV Ptr): OSErr;
  392. FUNCTION NavPutFile(VAR defaultLocation: AEDesc; VAR reply: NavReplyRecord; VAR dialogOptions: NavDialogOptions; eventProc: NavEventUPP; fileType: OSType; fileCreator: OSType; callBackUD: UNIV Ptr): OSErr;
  393. FUNCTION NavAskSaveChanges(VAR dialogOptions: NavDialogOptions; action: NavAskSaveChangesAction; VAR reply: NavAskSaveChangesResult; eventProc: NavEventUPP; callBackUD: UNIV Ptr): OSErr;
  394. FUNCTION NavCustomAskSaveChanges(VAR dialogOptions: NavDialogOptions; VAR reply: NavAskSaveChangesResult; eventProc: NavEventUPP; callBackUD: UNIV Ptr): OSErr;
  395. FUNCTION NavAskDiscardChanges(VAR dialogOptions: NavDialogOptions; VAR reply: NavAskDiscardChangesResult; eventProc: NavEventUPP; callBackUD: UNIV Ptr): OSErr;
  396. FUNCTION NavChooseFile(VAR defaultLocation: AEDesc; VAR reply: NavReplyRecord; VAR dialogOptions: NavDialogOptions; eventProc: NavEventUPP; previewProc: NavPreviewUPP; filterProc: NavObjectFilterUPP; typeList: NavTypeListHandle; callBackUD: UNIV Ptr): OSErr;
  397. FUNCTION NavChooseFolder(VAR defaultLocation: AEDesc; VAR reply: NavReplyRecord; VAR dialogOptions: NavDialogOptions; eventProc: NavEventUPP; filterProc: NavObjectFilterUPP; callBackUD: UNIV Ptr): OSErr;
  398. FUNCTION NavChooseVolume(VAR defaultSelection: AEDesc; VAR reply: NavReplyRecord; VAR dialogOptions: NavDialogOptions; eventProc: NavEventUPP; filterProc: NavObjectFilterUPP; callBackUD: UNIV Ptr): OSErr;
  399. FUNCTION NavChooseObject(VAR defaultLocation: AEDesc; VAR reply: NavReplyRecord; VAR dialogOptions: NavDialogOptions; eventProc: NavEventUPP; filterProc: NavObjectFilterUPP; callBackUD: UNIV Ptr): OSErr;
  400. FUNCTION NavNewFolder(VAR defaultLocation: AEDesc; VAR reply: NavReplyRecord; VAR dialogOptions: NavDialogOptions; eventProc: NavEventUPP; callBackUD: UNIV Ptr): OSErr;
  401. FUNCTION NavTranslateFile(VAR reply: NavReplyRecord; howToTranslate: NavTranslationOptions): OSErr;
  402. FUNCTION NavCompleteSave(VAR reply: NavReplyRecord; howToTranslate: NavTranslationOptions): OSErr;
  403. FUNCTION NavCustomControl(context: NavContext; selector: NavCustomControlMessage; parms: UNIV Ptr): OSErr;
  404. FUNCTION NavDisposeReply(VAR reply: NavReplyRecord): OSErr;
  405. FUNCTION NavServicesCanRun: BOOLEAN;
  406.  
  407. FUNCTION NavServicesAvailable: BOOLEAN;
  408. {$ALIGN RESET}
  409. {$POP}
  410.  
  411. {$SETC UsingIncludes := NavigationIncludes}
  412.  
  413. {$ENDC} {__NAVIGATION__}
  414.  
  415. {$IFC NOT UsingIncludes}
  416.  END.
  417. {$ENDC}
  418.